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2068 FROGRAMMER’S CARTRIDGE TOOLEIT 

This "toolkit" is a program which provides helpful utilities to aid in 
writing your own Basic programs. Because it comes on a cartridge, it offers 
the advantage of being instantly available (no loading from the cassette 
recorder). In addition, the toolkit requires only a tiny amount of RAM space 
so potential conflicts with other programs you use the toolkit with are kept 


to a minimum. 


To run the toolkit, make sure the computer is turned OFF. Then insert the 
cartridge into the dock connector which is under the door at the front of thi 
TS20468. Once the board is plugged in, turn the computer ON. The toolkit menu 
will come on the TV screen automatically. This menu lets you select one of 
the toolkit’s 8 Built-in functions. More about what these functions do and 


how to use them will be covered later. 


In general, all functions prompt you to input the information needed to 
execute the procedure. Performing a toolkit function, therefore, is a simple 
matter of selecting the desired menu option and entering the data which the 
computer asks you for. In addition, the toolkit will automatically LPRINT a 
hard copy of each step. If you use a full size printer with one of the & 
different printer interfaces this toolkit caters for, the first thing you 
will want to do after turning on the computer is configure the toolkit print 
driver to match your brand of interface. Then, you can have hard copy of the 
toolkit’s action printed out on your printer. 


If you use the TS2040 printer, or no printer at all, it will not be necessary 
to configure the print driver. However, if you have a printer interface 
Plugged into the computer, you should configure the print driver before using 
any of the other toolkit functions. Certain interfaces can cause the computer 
to hang up if this is not done. If you forget, and you find the computer just 
sits there without doing anything when it should be performing a function, 
you can always press BREAK and then enter RUN to start from the main toolkit 


menu again. 


If you prefer not to have the automatic LFPRINT feature so as not to consume 
paper, just turn the printer off. The toolkit will continue to LPRINT, but 
since the printer is not turned on, nothing gets put on paper. 
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DETAILS OF THE TOOLEIT FUNCTIONS 


OFTION 1. Block Line Renumberer 


This function will renumber a specified block of program lines in a Basic 
program. When you have a program in memory which needs renumbering, select 
option 1 from the main toolkit menu. The computer will first ask you for the 
"old starting line number". This represents the line in the program where 
renumbering is to begin. After you input the desired line number, the 
computer reports the following information about the line: the address of th 
line, its length, and its relative address which is the distance from the 


start of the program. 


Next, the computer asks you to input the "new starting line number". This ig 
the new value you want your block of program lines to start with. Third, the 
computer asks for the "step" which the space between line numbers. Entering 
step of "1" would result in program lines numbered 1, 2, 3, 4, etc. while a 
step of "S" would result in lines numbered 5, 10, 15, 20, 25, etc. After the 
step value is entered, the computer asks for the "old stopping number". This 
is the line number at which renumbering stops. The line with the old stoppin 
number WILL NOT be renumbered. The renumbered block ranges from the old 
starting number up to but not including the old stopping number. 


Qnce this information is input, the computer renumbers the specified lines. 
It prints "Renumbering complete" and takes you out of the toolkit, leaving 
you in the home bank with your Basic program. 


When you use the Line Renumberer, two important aspects must be remembered. 
First, Basic lines will be renumbered, but they will not be repositioned in 
the listing. This means that it’s possible to produce a line 1000 which come: 
before line SO if you’re not careful. This can result in problems when you 
try to edit or run the renumbered program. The best way to learn how to use 
the renumberer is to experiment with it by renumbering short "test" programs 
before you try it out on a long involved listing. 


Second, although program lines are altered, RESTORE, GO TO and GO SUB 
commands are not. They will need to be corrected manually. To make finding 
these lines which contain RESTORE, GO TO, and GO SUB easy to see, the 
renumberer places a big black square in each line after the command. After 
numbering is complete, you can go through the listing and edit the lines 


which .contain the square. 


You may find that you will want to use the renumber function just to obtain 
the information about the program line’s starting address and length without 
actually doing any renumbering. Other times, you may change your mind and 
decide not to renumber after you have selected the renumber function. Any 
time you wish to exit from this procedure without renumbering, just type in ¢ 
zero in response to a prompt. This will take you out of the renumberer and 


back to the main toolkit menu. 
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After a block of lines have been renumbered, and the computer takes you out 
of the toolkit and into your Basic program, you can get back into the toolkit 


by typing: 
PORE 223750,128: RUN or PORE 23750,128:GO TO 1 


The difference between these two commands is that RUN causes the computer to 
CLEAR any variables your program may be storing, while GO TO starts the 
toolkit executing without clearing any variables. In any event, it is the 
POKE which is important. When memory address 23750 is poked with a 128, any 
RUN, GOTO, CONT, or GO SUB will go to the toolkit. When 223750 is poked with a 
0, these commands will operate YOUR program in the home bank. 


OPTION 2. Hex/Dec Loader 


Selection 2 at the main toolkit menu turns on a handy utility which lets you 
read and write values to memory. You can use this for inputting those tedious 
machine code listings taken from magazines, or for checking your work after 
you have typed a listing in. The first question the computer asks you after 
you select option 2 is whether you intend to input Hex codes or Decimal 
codes. Your response should be either "H" or "D". Next the computer asks you 
for the address it is to start at. You can input this address either in Hex 
or in Decimal. This is done by prefixing the address with either a "H" or 
"D". For example, typing in "D6000" will signify a starting address of 4000 
decimal. "H6000" will signify 69000 hex. If you forget to type in the "D" or 
"H", the computer will ask you to type the address again. 


Once the starting address is properly input, the toolkit displays the address 
on the screen along with its current value. Displays are in both hex AND 
decimal. At the bottom of the screen, the prompt, "Hex Code?" or "Dec Code?" 
appears. At this point you can type in the value you wish to poke to the 
current address. You do not need to prefix your input with aH or D here. 
Just the number will do. 


Several more options are possible at this input. You can press just ENTER to 
skip the current address and proceed to the next one. You can enter just "H" 
or "D" to change the numbering system for inputting values (ex: if the 
computer asks you for a hex code, you can type "D" to make it ask you for a 
decimal code instead). You can enter "A", meaning "address" to have the 
loader start working at a completely new address. Finally, to exit the 
loader, you can type "@", or "STOP" (either the token or spelled out). Any 
one of these will cause the machine to go back to the main menu, but before 
you do, the computer asks if you wish to COFY the screen (only if you’re 
using the TS2040 printer) and if you want to go back to the loader for some 
more poking. These prompts will execute only if you press "Y". If you press 
"N" or any other key, the program assumes you mean "NO" and takes you back to 
the main toolkit menu. 


As your understanding of the TS2068 grows, you will find this loader utility 
very useful for much more that just entering machine code listings. With it, 
you can alter the contents of any RAM memory including Basic program lines, 
and variables. It is possible, for example, to use the loader to change a4 
string array into a simple string, or a numeric array into a string array. 
For fun, use the Hex/Dec Loader to input random values in the Attributes file 
which begins at decimal address 22528. Have fun! — 
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OFTION =. Disassembler 


The disassembler converts the values stored in memory as machine code into 
the more understandable mnemonic format. You can use it to find out just 
what ’s going on in the code you poke in using the hex/dec loader, or it will 
be helpful in unraveling the mysteries of the 2068 ROM. To use the 
disassembler, select option 3 at the main toolkit menu. The computer will 
then ask you to input the address at which you wish to start your 
disassembly. As in the Hex/Dec loader, precede your address with "H" or "D" 
depending on whether your address is a hex or a decimal number. 


Once an address is entered, the program will display in hex, the addresses, 
the actual byte values, and the mnemonic disassembly. The disassembly will 
fill the screen as it progresses until the bottom line is reached. You will 
then be given the prompt, "more? (Y/N/C/Q@)". You should enter a letter 
depending on what you want to do. Enter: 


Y-to continue the disassembly with the next address 
N-lets you type in a NEW starting address 

C-will COFY the screen 

Q-QUITs and returns you to the main menu 


OFTION 4. Tri-Base Arithmetic 


The fourth option turns your computer into a programmer’s multi-base 
arithmetic calculator capable of performing arithmetic on numbers in decimal, 
hexadecimal, or binary format, or even a combination of formats such as hex 
SA plus binary 101901. To perform calculations, you follow the sequence of 
inputting a number first, an operator second (+,-,*,/,=), a second number, 
and another operator (such as "="). The result of the calculation will appear 
on the TV screen in all three number systems: hex, binary, and decimal. 


To give you a better idea of the meaning of all this, here is an actual 
example. First press "4" and ENTER at the main toolkit menu to get into this 
mode. The computer will ask you for an "Input?" This can be a number 
preceded by a "H", "D", or "B" meaning HEX, DECIMAL, or BINARY respectively. 
Type in BOO119101 and ENTER. The computer takes this input and converts it to 
so decimal, 0025 hex, and of course, binary 00110101. All three numbers are 
printed on the screen. Now type in "+" and ENTER in response to the second 
"Input?" prompt. The plus sign will also go up on the screen. Next enter the 
number "H2E6A". As before, the number is converted to binary, hex, and 
decimal and it’s printed on the screen. Finally, press "=" and ENTER. This 
causes the two numbers to be summed and the result printed on the screen. At 
this point you could enter another "+" followed by another number to add it 
to this result, or you could just input a new number to start a new 
calculation. 


The ability to perform arithmetic in any combination of hex, decimal, or 
binary is very useful for machine code programmers. Suppose you need to 
reserve space for a 712 byte table at address 40EQhex? You can let this 
utility calculate where the end of the table will be located. If you don’t 
program in machine code because you can’t figure out the wierd number systems 
involved, Tri-Base can be a very useful study tool. The binary display will 
give you a very illustrative demonstration of what happens to a number as the 
computer processes it. 
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The example given of two numbers being added together demonstrates only a 
part of the many functions available in Tri-Base. Here is a more detailed 
list of items you can enter at the "Input?" prompt: 


Numbers-integers may be input in hex, decimal, or binary. Prefix the 
letters B or H to signify binary or hex. The letter D is optional for 
decimal inputs. If you de not precede a number with a letter, the com- 
puter assumes the number is decimal. Values must range between -65536 


and +65525. 


Negative numbers must be input as decimal numbers. Hex and Binary inputs 
must be positive, however once they are entered, they may be changed toa 
their negative by entering the "+/-" function. Enter the three char- 
acters, "+", "/", and "~" together to change the last value displayed 
to its opposite. This is known as the "change sign" function on other 


calculators. 


Arithmetic Operators-the customary "+", "—-", "/", "#", and "=" functions 
are available. These symbols are entered alone. After entry, they 
appear at the far left of the screen between the two rows of values to 
which they apply. As noted above, the "change sign" function (+/-) is 
also available. This serves to give the 2’s compliment of a number. 


Logical Operators-besides the arithmetic operators, you also have the 
logic operators, AND, OR, and XOR. Additionally, "C" gives the 1’s 
compliment of a number. These operators are entered the same way as 


the arithmetic operators. 


Chaining Operations-either arithmetic or logic operations may be 
chained (A+B+C+D). However, there is no hierarchy among operators, 
and no facilities for parentheses are provided. There is a single 
memory store available to help with more complex calculations. This 
memory is accessed by entering the commands "STO" which stores the 
last number displayed, and "RCL" which reclaims the value and puts 


it on the screen. 


Shift and Rotate Functions~-binary numbers can be shifted left or right 
by entering the commands "SR" or "SL". All 16 bits of a binary number 
will shift and the corresponding hex and decimal values will change 
accordingly. Binary numbers can also have their bits rotated. Do this 
by entering the commands "RRn" and "RLn" where the "n" signifies the 
number of bits to rotate. It is necessary to include the number of bits 
to rotate to provide flexibility in rotating 8 bit numbers in the same 
way that the Z80 microprocessor does. If, for example, n=8, the left 
most 8 bits will be set to zero and the rotation will occur using only 
the right most 8 bits. This simulates the RLC x and RRC x instructions 
of the Z80 except that no carry flag is set or reset. If n=9, the RL x 
and RR x instructions can be simulated with bit 8 (the 9th bit from the 
right) being used as the carry flag. 


Hard Copy-If your printer is connected and turned on (be sure to config- 
ure your print driver first if you’re using a big printer), all 
displays will be Lprinted as well as displayed on the TV. Also, if you 
use the TS2040, you can input the command "Z" or "COPY" to copy the en- 


tire TV screen. 


Returning to the main toolkit menu-is accomplished by entering the let- 
ter "OQ", the token "STOP", the word "STOF" spelled out, or the letter 
"A" when the computer asks "Input?" All commands perform the same fun- 
ction; they exit Tri-Base and return you to the Main Menu. 
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OFTION S. User Defined Graphics Generator 


This fun to use feature lets you create user defined graphics characters witt 
tremendous flexibility. The Graphic Generator screen shows an enlarged grid 
representing the 8 x 8 pixel arrangement of the first graphic character to be 
defined. The computer starts with the letter-A. However, you may change the 
character to any one you wish by typing a letter between A and U. 


Below the enlarged grid you will find two identical lines displaying letters 
from A to U. Each letter in the top line signifies one of the definable 
graphic characters. The letters in the bottom line display the graphic 
character itself. When you first start, the two lines are the same because 
you haven’t defined any new graphics yet. But as you create new characters, 
the "actual size" character will appear on the second line. 


Below this is a reference telling you the effects of various keypresses. To 

create a new graphic character, first select the letter you wish by pressing 
a letter between A and U. After this character is created, you can print it 

on the screen by getting the "G" cursor and then typing the letter you have 
selected. Information about how to do this is covered on page 162 of the 
52068 owners guide. 


Notice that in there is a tiny dot in the upper left square of the enlarged 
grid. This is a cursor which you can move about by pressing one of the arrow 
keys (on "5S", "6", "7", and "8"). When you press just an arrow key without 
holding down SHIFT, the cursor will move in the direction of the arrow. When 
you press SHIFT and an arrow, you will also move the cursor, but you will 
leave a trail of INK on the grid. You can also leave a trail of PAPER by 
pressing the Symbol Shift key and an arrow. 


The entire grid can be filled with either INK or PAPER by pressing Caps Shift 
and "i" (for INK) or Symbol Shift and "1" (for PAFER). You can also place a 
single spot of INK or PAPER at the cursor location by pressing either the 
me", "3", or "9" keys simultaneously with the SHIFT or Symbol Shift keys. 
SHIFT will produce INK and Symbol Shift produces PAPER. 


INK and PAPER can be reversed or toggled back and forth by pressing SHIFT 4 
or Symbol Shift 4. Every pixel which is INK turns to PAPER and that which is 
PAPER becomes INK. The result is a negative or reverse image of the character 


being created. 


To exit the Graphic Generator mode, or to clear out graphics you are not 
happy with, press SHIFT and "0". The computer will then ask you if you want 
to restore the original graphics. If you press "y" in response to this 
prompt, the effect is to erase every User Defined Graphic character and 
replace it with the original alpha character. The computer lets you start out 
with a clean slate. If you enter "n" in response to this prompt, the machine 
next asks you if you want to SAVE your graphics on tape. A "y" response here 
will cause the graphics to be saved so you can load them into another 
program. After a save, you can either go back to the main toolkit menu or 
create more graphics. If you do not save to tape, the program goes directly 
back to the main menu. Your user defined graphics will remain intact as long 
as you don’t turn off the computer. You can go back later to work on more 
UDG’s if you wish. 


OFTION 6: Header Reader 


The Header Reader function allows you to read the header data on cassette 
tapes. It provides information about what type of data is on the cassette 
like the Name, whether it is a Basic program, a character array, code, etc. 
Where applicable, the function tells what line the program will auto start 
from, the address and number of bytes of code, and the length of variables 
area of Basic programs. This type of information can be very useful if you 
are trying to break into a protected program to see how it works. The header 
reader‘’s analysis can be very informative in providing details about the 
nature of various programs, machine code, or data you have on cassette. 


When you select this option, the computer will ask you to play the tape you 
want to read. Once read, a display of all pertinent information is printed on 
the screen. If your printer is turned on, this data will also be Lprinted. I¢ 
you have set the toolkit for use with the TS2040 printer, you will also be 
given the option. to COPY the screen. After you respond to these prompts, you 
can either read another header or go back to the toolkit menu. 


OFTION 7: Configure Print Driver 


If you use a full size printer with your computer, you will definitely want 
to make use of the toolkit’s built-in Printer driver software. With it, you 
can LFRINT to using any of the 6 commercially available printer interfaces 
without having to load Separate cassette based driver software. Also, because 
the toolkit drivers are located in the dock bank, conflicts and 
incompatibility problems are kept to a minimum. 


To make use of the toolkit print drivers, select option 7 at the main Menu. 
This will cause a screen to come up which offers you a choice of interfaces. 
Enter the number representing the brand you use. Note that the last option is 
listed as "Other". This Gives you the ability to Provide your own driver 
program in the home bank should you use an interface which is not provided 
for. You will be asked to enter the entry point address of your custom 
driver. This is the address in the home bank where your driver is located. 


Once the brand of interface is selected, you are next asked if you want the 
computer to make the printer drop down a line whenever a carriage return is 
lprinted. With most printers, it is possible to set a switch on the printer 
itself to accomodate this, but sometimes, it is more convenient to have the 
computer do it for you. Experiment with the "y" or "n" responses to this 
Prompt to see how your printer reacts. 


Finally, the computer asks you to input which print mode you wish to use. As 
in selecting the brand of interface, type the number representing the desired 
mode. The three available modes let you Iprint in different ways. Each is 
useful in varying circumstances. Depending on your application, choose the 
mode which best fits your circumstances. Here’s a description of the function 


Of each mode: 


PAGE 8 


4 


MODE 1. Normal: 


All regular characters will be printed, and tokens like AT, FRINT, GO TO, 

STOP, etc. will be spelled out. Uses include virtually all that would work 
when using the TS2040 printer except you are not restricted to 32 columns. 
Examples are: 


LPRINT "Hello, there!" 

LFRINT at 

LPRINT .0125 

LFRINT x 

LPRINT TAB 40;"test"; TAB SO: "again" 
LLIST 

LLIST 1000 

LFRINT CHR 10 


The last example. above shows one way to send CHR 10, (LINE FEED) one of a 
group of special characters called "control codes" which cause the printer to 
perform some special function rather than to simply smack a letter out on 
paper. Two other methods of lprinting control codes are possible in this 
print mode. The top row of of your 2068 keyboard has 8 keys which can print 
graphics characters on the TV screen when you put the computer into the 
Graphics mode by pressing SHIFT and "9". The print driver will accept these 
characters, but instead of sending a character to be printed, a control code 
is sent in its place. You have, therefore, 16 possible codes you can send 
when you call up the "G" cursor and press one of the graphic keys. There are 
8 lower case graphics and 8 upper case graphics. The actual code sent to the 
printer can be determined by looking at the following table: 


Graphic on sends the code: which is the ASCII: 
the number: lower/upper case lower/upper case 

1 10 3 LF US 

2 11 30 VT RS 

3 12 29 FF GS 

4, 24 08 CAN BS 

S 14 Los so DCS 

ra) 15 11 , SI DC1i 

7 O1 13 HT CR 

8 27 27 ESC ESC 


These codes can be altered. The keys are assigned the above values when you 
decide to configure your printer interface, but if you prefer to set up your 
Own scheme, you can by POKING a few bytes of memory. Full details appear at 


the end of this section. 


Print mode number 1. also lets you create "Macro Commands" consisting of up 
to 8 different control codes or other characters. Lprinting just one code 
representing the macro will send all 8 control codes to the printer. Macros 
are created using the User Defined Graphics capabilities of the 2068. I¢ you 
study the Timex owner’s manual, you’ll discover that a user defined graphic 
Character is made up of 8 different bytes. To create a macro, define a 
graphic character so that it includes the control codes you wish to send to 
the printer. Then, when you lprint this character, each of the eight bytes 
which comprise the UDG character will be sent to the printer. 
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To give you a better idea of just how you might use a macro command when you 
lprint, consider this situation: Suppose you want to send the codes neceesary 
to make the printer start printing enlarged, proportional, underlined text. 
This would require 5 separate control codes for the Frowriter which I use. 
They are: 14-to SHIFT OUT ‘enlarged type), 27 and 80 (ESC F)-proportional 
spacing, and 27 and 89 (ESC U)-underline. 


It is possible to define a graphics character which when lprinted, will send 
all S necessary contrsl codes in one fell swoop. The Basic lines below create 
UDG’s for any desired letter between A and U, and lets you input the codes 
you want to send. Once you have created your own custom macros, they can be 
saved and loaded as User Defined Graphics and used in other programs. 


19 REM Routine for creating UDG Macro Commands 
=9 INPUT "Type a letter A-U";L# 

20 PRINT LS 

40 FOR X=0 TO 7 

JO PRINT X3"---—"s 

69 INPUT "Control Code? "3¥ 

70 PRINT Y 

80 POKE USR L#+X,Y 

90 NEXT X 


RUN this program and select the letter "A" in response to the prompt in line 
29. You'll next be asked to enter 8 control codes. These are the codes you 
want to execute. I would enter, for example, the numbers: 14, 27, 30, 27, 39, 


9, 9, 9 to make my Prowriter print enlarged underlined proportional 


You could also use the toolkit to define a Macro character. First, call up 
the Tri~Base Arithmetic option and note the binary sequence of 1’s and %’s 
for each of the control codes you plan to send. Then, use the UDG generator 
to fill in the pixels of your Macro character so that the binary 1’s are 
represented as INE while the O’s- are FAFER. If your Macro does not use all 8 
bytes of the UDG character, fill cut the unused bytes with O’s (PAPER). 


After a macro is created, send it by getting the G-cursor and typing the 
letter "A" (or whatever other letter your UDG is assigned to). When this 
character is lprinted, the 8 separate codes you input go to the printer. 


MODE 2: Up-Arrow Printing. 


This method of printing is called "Up-4rrow" because it involves the use of 
the up pointing arrow symbol (Symbol Shift-H). In this mode, normal ASCII 
characters (letters, numbers, and punctuation marks) are lprinted, but tokens 
are NOT spelled out. This makes mode 2 pretty useless for LLISTing. The 
advantage is that you can use mode 2 to lprint control codes embedded in a 
string of characters without the need for macros, definable graphics keys, or 
extra program lines. 


A situation could arise where you are running a program such as: 


INFUT A 
LERINT A+ 
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and you want to use the graphic keys for something besides printing control 
codes. This is precisely what happens in the Fro/File 2068 program. Graphic 
keys are used as file editing commands, and therefore, are not available for 
us@ aS control codes. Mode 2, gives you another way to place control codes 
right inside a string. This is done using the Up Arrow, and then immediately 
following this character with a two digit hex number representing the contrel 
code you wish to send. For example, to send the SHIFT OUT command embedded in 


a string, you could do something like this: 


LFRINT "This is a test“OEThis is another test” 


or 


LET Af="This is a test“OEThis is another test” 
LFRINT At 


The hex number which follows the "*" is OF or 14 decimal which is the SHIFT 
OUT control code. The Up Arrow acts as a trigger to signal to the print 
driver that the next two characters are digits of a hex number and are to be 
interpreted and sent as one code rather than two. 


MODE 3: Raw ASCII 


Some printers have extensive graphics character sets of their own which are 
accessed by sending codes greater than 128 in value. Whenever print mode 1 is 
used, all such codes are considered tokens which are to be expanded into 
words like FRINT or GO TO. In Mode 2, whatever code you lprint will go to the 
printer unmolested. Thus mode 7 makes it Possible to make use of those great 
graphic characters or itallics which are common on so many printers. This 
mode does not perform any interpreting of the code you lprint like modes 1 
and 2. Therefore, mode 2 is called the "Raw ASCII" mode. Examples of ways to 


use this mode include: 


LPRINT " TO TO STEP STOF " (sends the codes 204, 204, 217, and 224) 
LFPRINT CHR 2090 (sends the code 200) 


PRINT NOTES FOR PROGRAMMERS 


When you select the "Configure Print Driver" option of the Toolkit menu, the 
interface type, Carriage Return/Linefeed option, and print mode remain in 
effect until you change them by selecting this option again. All options, 
however, can be set from within your own basic program without the need for 
running the toolkit. Thus, as long as the cartridge is plugged into the 
computer, you can make use of the built-in driver software in your own 
programs. To do this, first turn on the computer and let the Toolkit self 
start. Select option 7 and configure the driver to your specifications. Then 
select option 8 of the Toolkit menu which returns you to the HOME bank. Load 
your own program. Any commands you have which LLIST or LFRINT will call the 


Toolkit print driver. 
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To change the print mode from within your own program, add the command 


. 
FORE 235327 .4x 


where xx equals 9 for NORMAL, 1 for UF ARROW, or 3 for RAW ASCII modes. 

To change the printer interface from within your own Basic, FORE 2TZzé.yy 
where yy equals 0 for AERCO, 1 for Tasman type-B, 2 for Tasman type-c, 4 for 
AZJ Centronics, S for Byte-Back Farallel, and 6 for OTHER. (Special note for 
machine code programmers: In the last case, OTHER, you must also have your 
Own print driver resident somewhere in the HOME bank of RAM, amd the starting 
address of your code must be poked into bytes 22321 and 25222. The toolkit 
print driver will call your code as a subroutine so you should end it with a 
RET instruction. The toolkit print driver will enter your code with the 
character to lprint is present in the C register.) ; 


A complete description of all variables used by the toolkit print driver 
appears below: 


Name Address Description 

FCGL 2o520 column number store 

JFAD fone address for OTHER print driver software 
COMD CES Up Arrow flag 

FLET Sa52 " 

CNT_ 22325 ” c 

VER_ foo I/F version: 


QM=Aerco, 1=Tasman(b), 2=Tasmani(c) 
4=ALJ, S=ByteBack,  6=OTHER 
Set Bit 7 for CR+LF, Reset Bit 7 for CR only 


MODE PET f Specifies Frint Mode: O=Normal. 1=Up Arrow, 2=Raw Ascii 
In ALL modes, codes 16 and 17 are treated as TAR 
GRAF oo Start of Graphics Key Table. Graphics on keys 1-8 ¢in 


MODE 1) are definable. Foke the addresses below with 
the value you wish to send: 


for key initial value control code 

GR-8 iB Escape 

GR-1 OF Line Feed 

GR-2 OE : Vertical Tab 
GR-= oc Form Feed 

GR-4 13 Cancel 

GR-5S OE Shift Out 

GR-6 OF Shift In 

GR-7 n> . Horizontal Tab 
Sh GR-1 OD Carriage Return 
Sh GR-2 1i Device Control i 
Sh GR-s 1s Device Control F 
Sn GR-4 og Back Soace 

Sh GR-S 1D Group Separator 
Sh GR-& 1E Record S5esarator 
Sh GR-?7 1F Umit Separator 
Sh GR-& 1B Escape 


STOR SAS Temporary storage for TAB spaces 


AUD Lo 
USING THE TOOLEIT WITH OTHER FROGRAMS 


It is the nature of toolkit type programs that they be used in conjunction 
with other programs also resident in memory. This is certainly possible with 
this program. Because this Cartridge Toolkit runs from a cartridge in the 
DOCK bank of the 2968, you still have virtually the entire HOME bank free to 
use for other Basic or machine code programs. 


The last option (Number 8) of the Toolkit menu gives you the ability to stop 
running the Toolkit and return you to whatever you may have present in the 
HOME bank. Once you make this selection, the Toolkit is turned off, and the 
computer does mot even know that the Toolkit is present in the cartridge. 


Any new Basic you execute; such as adding or editing program lines, LOADing 
or SAVEing, use of RUN or GO TO; will affect only the HOME bank of memory. 
This is what makes using the Frint Drivers in the cartridge so useful. All 
you have to do is turn on the computer, select the interface options you 
desire, then quit running the toolkit by selecting option 8 of the main 
Toolkit menu. At this point, you can LOAD the program you wish to actually 
use. Once it’s in memory, you can RUN it, change it, SAVE it or anything you 
want. The toolkit will not interfere in any way. But when you or your program 
try to LPRINT, the cartridge print driver will be called into action. 


GOING BACK INTO THE TOOLEIT 


Many times you will want to make use of some of the Toolkit options AFTER you 
load a program into the HOME bank. Obviously, the Basic line renumber 
facility is not very useful if you don’t have any Basic lines present! 
Therefore, it is clearly necessary to have a way to turn the toolkit back ON 
after it has been turned OFF. Here is how you do it. 


Enter the command: 


PORE 23750,12 
Can ber L 4 12 
eof, de 


PORE 


Either one will bring up the main Toolkit menu. If you use the first command 
which uses RUN, all variables stored in memory will be cleared before the 
menu comes up. If you do not want to clear away any variables, use the second 


command. 


These commands can also be included as program lines in your HOME bank 
program. In this way, the Toolkit can be called up automatically as a 
response to some sort of condition or input. Your HOME bank program could 
look something like: 


19 your program lines 

BO" 2 gave 

BO ere as 

40 PRINT "Press ‘T’ to start TOOLEIT" 

39 INFUT X# 

60 IF X#=2"T" THEN FORE 23750,128: GO TO 1 
72 your program lines 

BO wane 


FO Siete 


PAGE 13 


a 


CALLING SPECIFIC TOOLEIT OFTIONS 
DIRECTLY FROM WITHIN YOUR EASIC PROGRAM 


ieee 


In the above commands which turn the Toolkit ON, it is the FORE 22750,i28 
instruction which actually makes the computer recognize the program stored in 
the cartridge. The RUN or GO TO instructions simply tell the computer where 
te start running the Toolkit. A simple RUN or GO TO 1 starts the toolkit at 
the beginning. It is quite possible to turn the Toolkit on and go directly to 
one of the program options without displaying the main menu. All you have to 
change is the line number following the RUN or GO TO. A list of the necessary 


GO TO or RUN line numbers appears below. 
After you FORE 22759,128 enter: 


GO TO 190 or RUN 100 to start the Basic Line Renumberer 

GO TO 200 or RUN 200 to start the Hex/Dec Loader 

GO TO 200 or RUN FOO te start the Disassembler 

GO TO S00 or RUN 50OO to start the Tri-Base Arithmetic 

GO TO 600 or RUN 600 to start the UDG Generator 

GO TO 700 or RUN 700 to start the Header Reader 

GO TO 800 or RUN 800 to start the Print Driver Configuration 


PEERING INTQ THE CARTRIDGE 


You may be thinking, after looking at the above list of GO TOs, that the 
Toolkit cartridge must be some kind of a Basic program itself. That is 
exactly what it is (with a little machine code thrown in to speed things up a 
bit). What’s more, a provision has been added to enable you to LIST the 


program. 


This feature is rather restrictive in nature. Once you produce a listing, 
there is no hope of ever returning to either the HOME bank or the Toolkit 
program without switching OFF the computer. It is intended only to be a means 
for you to see what the Toolkit program looks like. 


To LIST the program, select option 83 of the Toolkit menu which turns the 
utility OFF. Then, enter the following command: 


POKE 23750,128:RUN 97998 


This causes a line in the cartridge (line 9998) to fool the computer into 
thinking that the Cartridge program is really in the HOME bank. The computer 
is able to read the memory in the Eprom, but nothing will happen when it 
tries to write to it. 

What happens after you RUN 9998 is the computer will will LIST on the TY 
screen. After the screen fills, you get the familiar "Scroll?" promt al the 
bottom of the screen. You can continue the normal scrolling of the program 
listing, you can stop scrolling, and you can move the line cursor up or down 
by pressing the arrow keys. But since the computer is reading memory from an 
eprom, you cannot print anything else on the screen. If you try, the "Er" 
cursor will simply vanish until you press enter, at which point, it starts to 
flash again. 


es] 
iS 


RUNNING YOUR OWN MACHINE CODE 

WITH THE TOQLIMIT 

There is a very serious bug in the TS20468 ROM which 

addresses which can be used for USR calls when you have any cartridge progranr, 
frond 


c s 
Plugged inte the computer. For this reason, machine code resident in the HOME 
bank may not function properly when th 


he cartridge is plugged in. Since many 
of you will be using the Toolkit with Machine code added in the HOME bank, 
you will Ge happy to learn that the Toolkit includes a method which 
circumvents the ROM bug and allows you to call machine code located anywhere 
in memory. You will need to go through the Basic which calls the machine code 
and change all the USR instructions slightly, however. Here is what you must 


severely restricts 


t 


cade: 
1. Load the system variable SEED with the starting address of your 
machine code. This would be the mumber following the USR function. 
The @asiest way to do this is to use the RANDOMIZ 
command: RANDOMIZE XX where "XX"-is your starting address. 
S. Execute the command RANDOMIZE USR 25088. 
As an actual example, consider the lines below: 
Change this listing to... this. 
10 LET 4A=o 10 LET A=o 
20 PRINT A: LET B$="DECEMBER" 20 PRINT A: LET B#="DECEMBER" 
ZQ RANDOMIZE USR S2eo0a =] RANDOMIZE S2?00: RANDOMIZE USR 2508S 
When this is done, machine code at address 25088 enables the HOME bank and 
ls, the 


0 
calls the address stored in SEED. As in normal machine language ca 
address stored in SEED. As in normal machine language calls, th 
returns with the contents of the EC register. 


+] 
RY fare bien 


TIFS AND HINTS 
Dealing With Errors 


A great deal of error trapping has been incorporated into the Toolkit, 5 
mothing is 190% fool-proof. If you find that you have typed in something 
which causes the computer to stop with an error report like "Variable not 
found" or "Nonsense in Basic", there are several ways to get the program 
running again. First, and also the simplest, is to start over completely by 


switching the computer OFF and then turning it back ON again. Executing the 
NEW command has the same effect. The computer will completely reset itself 


and start rumning again. 


You may not want t rastic action if you have a lengthy program 
loaded into the HOME bank. To do so would make it necessary to load the 
sragram back into the mputer. As am alternative, enter the RUN if or GO To 
e 4 
19 to produce th o to main menu again. Or, use the list of RUNs and GO 

4 
TOS given previous along with the approp 
f hz 


1 riate line mumbers to put you back 
at the start of the function you were wor 


i 
ing on when the error occured. 


that here, you do not need to FORE 22750,128 before you start the 


Note 

toolkit going. When an error stops a cartridge program, the cartridge is 
still turned ON aven though the program has stopped. A simple RUN or GO TO i: 
all it takes te get it started again. 


you have turned OFF the cartridge by = 
7SO with the value 128 before going & 


A Bit About Basic Variables 


If you follow the procedure for making the Toolkit LIST itself, you will 
notice that the program uses many Basic variables in the course of its 
operation. In fact, almost every letter of the alphabet is used for both 
string and numeric variables! In most cartridge type programs, this could 
pose a problem if you try to store a second program in the HOME bank which 
uses the sameé variable nmames. You would never know if, by runming the progra 


in the cartridge, you altered the value of a variable of the same name in th 
HOME bank program. 


The Toolkit gets around this situation by keeping the variables used in each 


= 


if 
€ 


program completely separate. Even though the Toolkit usés a string called OQ, 


you can load a program into RAM which also has a Qf. The computer will not 

get them mixed up. The way inwhich this works is fairly simple. Whenever you 

start the toolkit by running or going to one of the previously listed line 

numbers, the program turns on the Teolkit’ variables (this is done by the 

subroutine at 9997). When the program goes back to the HOME bank in the 
& 


normal way (@.g. Option 8 of the main menu, or at the completion of the Basi 
line renumberer), the HOME variables are restored (by line 905). 

As long aS you enter and exit the Toolkit "according to the directions" you 
won't have any problems with the computer confusing HOME and Toolkit 
variables. There are a few "backdoor" methods to get into or out of the 
program, Nowever, amd they are guaranteed to cause problems if you try them. 


he ways NOT to enter or @xit the Toolkit. The 
savioasd in the HOME bank may be altered as a 
gram leaded into the HOME bank, however, 


For your imformation, here are t 
values of variables used by a pr 
result. If you de not have a pro 
there is no ill effect. Feel 


DO NOT start the program by poking 2I750,128 and going to some odd ball 

program line not in the previous list. 

DO NOT exit the Toolkit by intentionally stopping the program with an error 
and then using PORE 23750,0. This is a very legitimate way to turn OFF an 
AROS cartridge, but in the case of the Toolkit, doing $0 will not restore 
the HOME See Variables! To properly restore the variables, you must exit 
the cartridge by s@lecting option 8 of the main Toolkit menu. 


ffi 


